Publishing

Going live

Up until now, every time we have looked at Frontier's output in our browser, we have done it through the Preview Page command. This command, however, is useful only up to a point.

The HTML documents that it makes are placed into folders in a sort of catch-all folder called Websites, in the same folder as Frontier itself; this folder (Websites) is really just a temporary holding place, and you should throw it away from time to time. A "real" rendering of your site would go into a folder you specifically designate with #ftpSite.

Even more important, "real" rendering gives you a way to render your entire site at once.

And we are coming now to some features of Frontier's Web site management that really make sense only in terms of the site as a whole, so it would drive you mad to have to render the site one page at a time.

"Real" rendering of this kind is called "publishing." It is a little more work than previewing a page, but not much. You select a single page and choose Publish Page from the Web menu, or, to render your whole site at once, select anywhere in your site (anywhere that isn't itself a table) and choose Publish Table.

But don't try it yet, because first we have to prepare our #ftpSite.

Where to build your site

Open the myFirstSite.#ftpSite table and look inside.

The #ftpSite.method entry reads "file" -- that tells Frontier it should create the pages onto a local file system.

You could also set the method to be "odb," which allows you to publish directly to an address in your Frontier root. On Macintosh, you can change the method to "ftp," and your pages will be automatically uploaded to a remote server. (This feature is coming soon for Windows, too.)

We need now to set the two values #ftpSite.folder and #ftpSite.url.

The value at #ftpSite.folder represents the folder on your hard disk into which Frontier will place the Web pages as they are rendered. A default value has been silently created for you, so that you could start publishing if you wanted to. But now we want to give it a real value.

(The default value is to publish into the Websites folder that's in the Frontier folder. But that's really where page previews should go, and not your published sites.)

Unfortunately, it's tough to remember and type an entire pathname accurately, especially when you're looking at it in such a small space. Here is a handy shortcut; it involves talking to Frontier in UserTalk, though, so I'm not going to explain what you're actually doing.

Go to your desktop and create the folder you want to render into, if it doesn't exist already. Now come back to Frontier and, from the Main menu, choose Quick Script. The Quick Script window appears (this is Frontier's "command-line" interface). If there's anything in it, select and backspace to get rid of it, and now type exactly the following:

   file.getFolderDialog 
    ("", @websites.myFirstSite.["#ftpsite"].folder)

Hit the Run button at the right of the QuickScript window, and use the resulting dialog to select the desired folder; its path will then have been entered as the value of #ftpsite.folder.

As for #ftpSite.url, this will be used by Frontier for various tasks where it needs to know the actual URL your site will occupy when it's on the Internet. If you know what this is, you should type it in for the value of #ftpSite.url now. Remember to put "http://" or "file:///"; in other words, if your site will be located at http://www.borg.com/mysite/, put "http://www.borg.com/mysite/" (without the quotes).

Now you can close #ftpSite and forget about it.

Publishing your entire site

Let's try publishing the whole site now. If you have been following along in this tutorial, you've made many changes in our practice site, so let's go back and clean up and take stock for a moment, so that we're working with the same set of documents.

You should have a default page whose #title is "Welcome." You should have a secondPage whose #title is "My Second Page" and which contains a renderObject macro which embeds thirdPage. You should have a thirdPage which is an outline, has no #renderOutlineWith directive, and has no #title. And you should have a fourthPage which is an outline, and has a #renderOutlineWith "tableOutliner" directive; I believe we neglected to give this a #title so call it "My Fourth Page."

Now select anywhere in the site table (but don't select anything that's a table!) and choose Publish Table. After checking with you to make sure you really want to do this (and to make sure it's got the right table), Frontier will churn away for a moment, and then open a page from the table you just published in your browser.

You can go to the folder and double-click any of the .html files to open them with your browser. (On a Mac you may need to change the value of user.html.prefs.textFileCreator to match the creator code for your Web browser.)

Site structure

A thing you should experiment with at this point is the way the structure of the whole site on disk mirrors the structure of the whole site in the table.

To see this, try putting fourthPage in a table of its own. In myFirstSite, make a new subtable using New Sub-Table from the Table menu. Call it "sub" (without the quotes). Cut fourthPage out of myFirstSite and paste it into the "sub" table. (Get rid of any "item #1" entry that may have arisen.) Now go back to the myFirstSite table and publish the whole site, and examine its structure. There is a subfolder called "sub," and fourthPage.html is inside it, just as in the site table.

Now move fourthPage out of the "sub" table back into the myFirstSite table, and delete the "sub" table. Publish the whole site. Ooops! The "sub" table is still there, with a copy of fourthPage.html still inside it!!

Frontier creates files and folders to reflect the structure of your site table, but it does not get rid of any files and folders (except when they are overwritten by the creation process).

Hiding things

There's another problem. We have rendered thirdPage, as thirdPage.html. Since the only purpose of thirdPage right now is to be an element embedded in secondPage, we need to "hide" thirdPage somehow so that it doesn't get included in the publishing.

Let's fix this. Cut thirdPage out of the myFirstSite table, open myFirstSite.#tools (create it if it doesn't exist) and Paste thirdPage in there. (Get rid of any "item #1" entry that may have arisen.)

Now, go back into secondPage and change its reference to thirdPage (in the renderObject call) so that it correctly reaches thirdPage; otherwise secondPage won't include thirdPage, as it is supposed to. By now I shouldn't have to tell you how to do this, so it is left as an exercise.

Publish the site again. You should find that secondPage is able to include thirdPage but thirdPage has not been rendered as a separate file. That's what we wanted.

Things inside the tools, images, and glossary folders are not rendered when a site is published.

Publishing via FTP

If you like, you can combine publishing and uploading via FTP. You do this by adding some new entries to your #ftpSite table, then changing the value of "isLocal" in your #ftpSite table to "false" (no quotes), starting up Fetch or Anarchie and your browser, and publishing in the normal way.

What are the entries you need to add to the #ftpSite table? You already have "folder," which is the folder on your hard disk where you do local releases; now you add "directory," which is the path (using slashes as separators) to the directory on the remote machine where you will put the material (since one often does not enter an FTP site at the directory used for Web stuff).

You already have "URL," which tells how Web users see your material; now you add "domain," which is the machine as seen by your FTP client. And you need "account" (your FTP username) and "password."

The most important thing to change is "method" -- if you're publishing via ftp, the method should be "ftp."

An example:

account	joestrummer
directory	/usr/www/apache/htdocs/
domain	207.25.71.29
folder	Macintosh HD:My Websites:
isLocal	false
method	ftp
password	hitsvilleuk
url	http://www.jones.com/

When I choose Publish Page, Frontier publishes the page and its images into the local folder (using the folder entry), then uses my FTP client to upload them (using the domain and the directory entries), then uses my browser to show me the page over the net (using the URL entry).